home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan 2 / Opus 5 - Magellan 2.iso / DOpus_SDK_5.5 / docs / memory.doc < prev    next >
Text File  |  1996-09-05  |  5KB  |  157 lines
  1. TABLE OF CONTENTS
  2.  
  3. dopus5.library/AllocMemH
  4. dopus5.library/ClearMemHandle
  5. dopus5.library/FreeMemH
  6. dopus5.library/FreeMemHandle
  7. dopus5.library/NewMemHandle
  8. dopus5.library/AllocMemH                             dopus5.library/AllocMemH
  9.  
  10.     NAME
  11.         AllocMemH - allocate memory using pooling routines
  12.  
  13.     SYNOPSIS
  14.         AllocMemH(handle, size)
  15.                     A0     D0
  16.  
  17.         void *AllocMemH(APTR, ULONG);
  18.  
  19.     FUNCTION
  20.         This function allows you to allocate a chunk of memory. The type of
  21.         memory allocated was specified when the memory handle was created.
  22.         The size of the allocation is tracked automatically (similar to
  23.         AllocVec).
  24.  
  25.         You can actually use this function with a NULL memory handle - in this
  26.         case, the function performs much like AllocVec(). This disadvantage
  27.         to this is that you are unable to specify the type of memory you need
  28.         (the default is MEMF_ANY|MEMF_CLEAR). Memory allocated in this way can
  29.         obviously not be tracked, and you must FreeMemH() each allocation
  30.         individually.
  31.  
  32.     INPUTS
  33.         handle - memory handle (from NewMemHandle())
  34.         size - the amount of memory to allocate
  35.  
  36.     RESULT
  37.         Returns a pointer to the memory block for you to use, or NULL if
  38.         the request could not be satisfied.
  39.  
  40.     SEE ALSO
  41.         NewMemHandle(), FreeMemH()
  42.  
  43. dopus5.library/ClearMemHandle                   dopus5.library/ClearMemHandle
  44.  
  45.     NAME
  46.         ClearMemHandle - free all memory allocated via a handle
  47.  
  48.     SYNOPSIS
  49.         ClearMemHandle(handle)
  50.                          A0
  51.  
  52.         void ClearMemHandle(APTR);
  53.  
  54.     FUNCTION
  55.         This function frees all memory that has been allocated with
  56.         AllocMemH() via the specified handle. The memory handle itself
  57.         remains intact.
  58.  
  59.     INPUTS
  60.         handle - memory handle (from NewMemHandle())
  61.  
  62.     SEE ALSO
  63.         NewMemHandle(), AllocMemH(), FreeMemHandle()
  64.  
  65. dopus5.library/FreeMemH                               dopus5.library/FreeMemH
  66.  
  67.     NAME
  68.         FreeMemH - free memory allocated with AllocMemH()
  69.  
  70.     SYNOPSIS
  71.         FreeMemH(memory)
  72.                    A0
  73.  
  74.         void FreeMemH(APTR);
  75.  
  76.     FUNCTION
  77.         This function frees an individual memory chunk that was allocated
  78.         using AllocMemH().
  79.  
  80.     INPUTS
  81.         memory - memory address returned from AllocMemH()
  82.  
  83.     SEE ALSO
  84.         NewMemHandle(), AllocMemH()
  85.  
  86. dopus5.library/FreeMemHandle                     dopus5.library/FreeMemHandle
  87.  
  88.     NAME
  89.         FreeMemHandle - free a memory handle completely
  90.  
  91.     SYNOPSIS
  92.         FreeMemHandle(handle)
  93.                         A0
  94.  
  95.         void FreeMemHandle(APTR);
  96.  
  97.     FUNCTION
  98.         This function frees all memory that was allocated using the specified
  99.         handle, and then frees the handle itself.
  100.  
  101.     INPUTS
  102.         handle - memory handle from NewMemHandle()
  103.  
  104.     SEE ALSO
  105.         NewMemHandle(), ClearMemHandle()
  106.  
  107. dopus5.library/NewMemHandle                       dopus5.library/NewMemHandle
  108.  
  109.     NAME
  110.         NewMemHandle - allocate a new memory handle
  111.  
  112.     SYNOPSIS
  113.         NewMemHandle(puddle_size, thresh_size, type)
  114.                          D0            D1       D2
  115.  
  116.         APTR NewMemHandle(ULONG, ULONG, ULONG);
  117.  
  118.     FUNCTION
  119.         This function allocates a new memory handle, to enable easy access to
  120.         memory pooling and tracking functions.
  121.  
  122.         If you wish to use the OS memory pooling routines, specify a puddle
  123.         and a threshhold size for the memory pool. If you do not specify
  124.         these, the memory handle will use ordinary memory allocations and
  125.         keep track of these via a linked list. A linked list will also be
  126.         used if the creation of a memory pool fails for any reason.
  127.  
  128.         You must specify the type of memory you want when you create the
  129.         handle. All memory allocated with this handle will be of the requested
  130.         type (ie you can not mix fast and chip memory within the same handle).
  131.         The normal MEMF_ flags are used for this, with the following notes:
  132.  
  133.           - If MEMF_CLEAR is specified, the AllocMemH() routine clears the
  134.             memory itself (as the OS pooling routines do not support this).
  135.  
  136.           - If MEMF_PUBLIC is specified, it indicates that you want the memory
  137.             handle to be shareable between tasks, and the allocation routines
  138.             will use semaphore locking when accessing the handle.
  139.  
  140.         The dopus5.library is linked with the standalone memory pool routines,
  141.         and therefore these routines work under OS37 as well as OS39.
  142.  
  143.     INPUTS
  144.         puddle_size - size of puddles to use for pooling, or 0 for no pools
  145.         thresh_size - allocation threshhold size for pooling
  146.         type - type of memory to allocate
  147.  
  148.     RESULT
  149.         Returns a memory handle for use with the other memory functions, or
  150.         NULL for failure.
  151.  
  152.     SEE ALSO
  153.         AllocMemH(), ClearMemHandle(), FreeMemH(), FreeMemHandle(),
  154.         exec.library/AllocPooled(), exec.library/FreePooled(),
  155.         exec.library/CreatePool(), exec.library/DeletePool()
  156.  
  157.